ParcelLabel API

The following information is intended to assist integrating merchants who use NZ Post by outlining operational processes that may affect how the ParcelLabel API is used.

1. The label formats produced by the ParcelLabel API comply with the addressing standards for NZ Post carriers (ParcelPost, CourierPost, and Pace). These formats cannot be modified for specific customers or used for other carriers. Labels are generated in either .pdf or .png format, depending on what is requested. It is the sender’s responsibility to print the label so that it can be affixed to the package and so that the printed barcode is of sufficient resolution to be scanned.
2. Thermal labels are recommended, as they present a professional appearance and ensure the label remains securely attached throughout transit. Laser printers will also produce the required resolution. Ink‑jet printers cannot be used. If labels are printed on plain paper (rather than thermal adhesive labels), the paper must be securely attached to the parcel. It is recommended that plastic sleeves are used, with the printed page folded and inserted inside.
3. It is possible to request multiple labels within a single request. The consignment_id returned in the response identifies the consignment (the complete group of labels), not an individual label. Individual labels are identified by the consignment_id followed by a sequence number—for example, XYZ123‑1 identifies the first label in consignment XYZ123. A consignment consists of multiple parcels being picked up from one location and delivered to a single location.
4. When Pace is the carrier, a Pace job number is required as part of the label request. This job number may be created through the ParcelPickup API process.
5. The service code required in a label request can be obtained via the ShippingOptions API. If the ShippingOptions API is not being used, please speak to your NZ Post Salesperson for a list of service codes.
6. It is the merchant’s responsibility to use the is_collection flag to indicate when a delivery address is an NZ Post collection point so that the correct label can be generated. Please refer to the ParcelAddress locations resource for further details about collection point locations.
7. If the delivery address used for labelling is an NZ Post collection point, you must create a PCD‑type subscription for the parcel recipient using the ParcelNotification API. This requires the tracking reference from the label, the parcel recipient’s first and last names, their email address, and the collection point’s location ID.

Use of Company Logos on Labels

CourierPost and Pace labels can include company logos within the label image. The following rules apply to the use and placement of logos:

1. Merchants who have applied and been approved to display their logo must provide a .png file sized 1480 px wide × 380 px high to the API Support team api@nzpost.co.nz.
2. Upon receiving the logo, NZ Post will assign a unique logo ID to the merchant. The merchant must supply this ID in the logo_id parameter for the logo to appear on the generated label.
3. If the provided logo ID does not exist, is invalid, or is associated with another merchant, the label will be generated without a logo.
4. In the unlikely event that NZ Post cannot retrieve the logo for technical reasons, the label will be generated without a logo.
5. Merchants may have more than one logo, each associated with a unique logo ID. It is the merchant’s responsibility to provide the correct logo ID with each label request.
6. If the parcel contents are identified as dangerous goods, the merchant logo will not be displayed on the label.
7. The use and placement of logos is at NZ Post’s absolute discretion. NZ Post may remove or decline to apply a logo at any time, for any reason, including if NZ Post believes that the logo may damage or diminish its reputation.